(nnchoke-retrieve-headers ARTICLES &optional
GROUP SERVER FETCH-OLD)Message-IDs. Current back ends do not
fully support either—only sequences (lists) of article
numbers, and most back ends do not support retrieval of
Message-IDs. But they should try for both.
The result data should either be HEADs or
NOV lines, and the result value should
either be headers or nov to reflect
this. This might later be expanded to various,
which will be a mixture of HEADs and NOV
lines, but this is currently not supported by Gnus.
If fetch-old is non-nil it says to
try fetching “extra headers”, in some meaning of
the word. This is generally done by fetching (at most)
fetch-old extra headers less than the smallest
article number in articles, and filling the gaps
as well. The presence of this parameter can be ignored if the
back end finds it cumbersome to follow the request. If this
is non-nil and not a number, do maximum
fetches.
Here's an example HEAD:
221 1056 Article retrieved.
Path: ifi.uio.no!sturles
From: sturles@ifi.uio.no (Sturle Sunde)
Newsgroups: ifi.discussion
Subject: Re: Something very droll
Date: 27 Oct 1994 14:02:57 +0100
Organization: Dept. of Informatics, University of Oslo, Norway
Lines: 26
Message-ID: <38o8e1$a0o@holmenkollen.ifi.uio.no>
References: <38jdmq$4qu@visbur.ifi.uio.no>
NNTP-Posting-Host: holmenkollen.ifi.uio.no
.
So a headers return value would imply that
there's a number of these in the data buffer.
Here's a BNF definition of such a buffer:
headers = *head
head = error / valid-head
error-message = [ "4" / "5" ] 2number " " <error message> eol
valid-head = valid-message *header "." eol
valid-message = "221 " <number> " Article retrieved." eol
header = <text> eol
(The version of BNF used here is the one used in RFC822.)
If the return value is nov, the data buffer
should contain network overview database lines.
These are basically fields separated by tabs.
nov-buffer = *nov-line
nov-line = field 7*8[ <TAB> field ] eol
field = <text except TAB>
For a closer look at what should be in those fields, see
Headers.
(nnchoke-open-server SERVER &optional
DEFINITIONS)(VARIABLE
VALUE) pairs that define this virtual server.
If the server can't be opened, no error should be signaled. The back end may then choose to refuse further attempts at connecting to this server. In fact, it should do so.
If the server is opened already, this function should
return a non-nil value. There should be no data
returned.
(nnchoke-close-server &optional
SERVER)nil if the server
couldn't be closed for some reason.
There should be no data returned.
(nnchoke-request-close)nntp-server-buffer, though.) This function is
generally only called when Gnus is shutting down.
There should be no data returned.
(nnchoke-server-opened &optional
SERVER)nil value. This
function should under no circumstances attempt to reconnect
to a server we have lost connection to.
There should be no data returned.
(nnchoke-status-message &optional
SERVER)There should be no data returned.
(nnchoke-request-article ARTICLE &optional GROUP
SERVER TO-BUFFER)Message-ID or a number. It is optional whether
to implement retrieval by Message-ID, but it
would be nice if that were possible.
If to-buffer is non-nil, the
result data should be returned in this buffer instead of the
normal data buffer. This is to make it possible to avoid
copying large amounts of data from one buffer to another,
while Gnus mainly requests articles to be inserted directly
into its article buffer.
If it is at all possible, this function should return a
cons cell where the car is the group name the
article was fetched from, and the cdr is the
article number. This will enable Gnus to find out what the
real group and article numbers are when fetching articles by
Message-ID. If this isn't possible,
t should be returned on successful article
retrieval.
(nnchoke-request-group GROUP &optional SERVER
FAST INFO)If fast, don't bother to return useful data, just make group the current group.
If info, it allows the backend to update the group info structure.
Here's an example of some result data and a definition of the same:
211 56 1000 1059 ifi.discussion
The first number is the status, which should be 211. Next is the total number of articles in the group, the lowest article number, the highest article number, and finally the group name. Note that the total number of articles may be less than one might think while just considering the highest and lowest article numbers, but some articles may have been canceled. Gnus just discards the total-number, so whether one should take the bother to generate it properly (if that is a problem) is left as an exercise to the reader. If the group contains no articles, the lowest article number should be reported as 1 and the highest as 0.
group-status = [ error / info ] eol
error = [ "4" / "5" ] 2<number> " " <Error message>
info = "211 " 3* [ <number> " " ] <string>
(nnchoke-close-group GROUP &optional
SERVER)There should be no data returned.
(nnchoke-request-list &optional
SERVER)Here's an example from a server that only carries two groups:
ifi.test 0000002200 0000002000 y
ifi.discussion 3324 3300 n
On each line we have a group name, then the highest article number in that group, the lowest article number, and finally a flag. If the group contains no articles, the lowest article number should be reported as 1 and the highest as 0.
active-file = *active-line
active-line = name " " <number> " " <number> " " flags eol
name = <string>
flags = "n" / "y" / "m" / "x" / "j" / "=" name
The flag says whether the group is read-only
(‘n’), is
moderated (‘m’), is dead
(‘x’), is
aliased to some other group (‘=other-group’) or none of the
above (‘y’).
(nnchoke-request-post &optional
SERVER)There should be no result data from this function.